Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / Using Transform Objects

Getting, Setting, and Modifying the Transform Clip

The clip shape that you specify in a transform object controls the clipping of shapes associated with that transform. The transform clip must be a primitive shape; primitive shapes are described in the geometric operations chapter of Inside Macintosh: QuickDraw GX Graphics. QuickDraw GX provides a pair of functions (GXGetTransformClip, GXSetTransformClip) that get and set the clip of a
specified transform, and another pair (GXGetShapeClip, GXSetShapeClip) that
get and set the clip of the transform associated with a specified shape.

QuickDraw GX also provides another set of functions with which you can easily modify a clip shape using constructive geometry. Table 6-2 shows the constructive geometry operations you can perform between a transform clip and another shape, in order to modify the clip shape.

Table 6-2 Constructive geometry operations between transform clips and other shapes

Function	Description
GXUnionTransform	Modifies the clip shape to be the union of it with another shape. Described on page 6-49.
GXIntersectTransform	Modifies the clip shape by intersecting it with another shape. Described on page 6-50.
GXDifferenceTransform	Modifies the clip shape by subtracting another shape from it. Described on page 6-51.
GXReverseDifferenceTransform	Modifies the clip shape by subtracting it from another shape. Described on page 6-52.
GXExcludeTransform	Modifies the clip shape by combining it with another shape in an exclusive-OR (XOR) operation. Described on page 6-53.

To use constructive geometry operations, the clip shape and the shape with which to operate must meet these criteria:

• The clip shape must be a primitive shape and cannot be a picture shape, text shape, or layout shape. (These criteria are automatically met if it is a clip shape.)
• The shape with which to operate cannot be a bitmap shape or picture shape. It should also be a primitive shape, because only its geometry and fill properties are used in the operation.
• If the clip shape's fill is even-odd fill or winding fill, or the inverse of these, the shape with which to operate must also be filled.
• If the clip shape is frame filled, a pen width of 0 is implied, indicating a hairline width to the clip frame. Hairlines are described in the geometric styles chapter of Inside Macintosh: QuickDraw GX Graphics.

Figure 6-8 shows several examples of the effects of these operations with a polygon clip combined with a rectangle shape. The figure also shows which combinations of fill types are allowed for each operation.

Figure 6-8 Constructive geometry operations with a polygon clip and a rectangle shape[Missing image]

Note

Figure 6-8 does not show a filled clip with a framed shape because this combination of shapes generates an error for any constructive geometry operation.

The following example shows how to create a clip using a constructive geometry operation. The clip is first created as a path shape and assigned to the transform object with GXSetTransformClip. That clip is then unioned with another path shape, using GXUnionTransform. The geometries of the paths (path1Geometry and path2Geometry) are not shown.

gxShape clipShape, pathShape;
gxTransform myTransform;
.
.  /* get or create the transform (not shown) */
.
clipShape = GXNewPaths ((gxPaths *)path1Geometry);
GXSetTransformClip(myTransform, clipShape);
GXDisposeShape(clipShape);

pathShape = GXNewPaths ((gxPaths *)path2Geometry);
GXUnionTransform(myTransform, pathShape);
GXDisposeShape(pathShape);

Note that only the geometries of the two path shapes matter; style information is not considered. The GXGetTransformClip function is described on page 6-43. The GXSetTransformClip function is described on page 6-44.